StartDrag

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODDragAndDrop

StartDrag
The StartDrag method initiates a drag operation.
ODDropResult StartDrag (in ODFrame srcFrame,
                        in ODType imageType, 
                        in ODByteArray image,
                        out ODPart destPart, 
                        in ODByteArray refCon);
srcFrame
A reference to the frame in which the drag is initiated.
imageType
A platform-specific drag-image type indicating the type of image OpenDoc should display to the user as dragging feedback.
image
A byte array whose buffer contains the data of the image being dragged.
destPart
If the drop was successful, this parameter contains a reference to the destination part. Otherwise, the content of this parameter is undefined.

Use of the destPart parameter value is restricted in this release of OpenDoc. You can do object pointer comparisons to check if a drop occurred in your part. However, you should not call any of the destination part's methods except for its Release method.
refCon
A byte array whose buffer contains extra platform-specific information needed for dragging.
return value
A value indicating the result of the drag-and-drop operation.

DISCUSSION
If your part initiates a drag, you should call this method after copying data from the drag item into the content storage unit for this drag-and-drop object. If the drag item includes any frames, you should call the SetDragging method for each frame to prevent it from being dragged into itself.
The content of the image parameter's buffer depends on the drag-image type. The only drag-image type supported on the Mac OS platform is a handle to a drag region (kODDragImageRegionHandle), as required by the Mac OS Drag Manager. For that drag-image type, the buffer contains the Mac OS RgnHandle value that is the handle of the drag region; the drag region is in global coordinates.
The data in the refCon parameter's buffer is platform-dependent. On the Mac OS, the buffer contains an ODEventData structure representing the mouse-down event that initiated the drag operation. This structure is needed by the Mac OS Drag Manager.
During the drag operation, the platform-specific drag manager displays the image specified in the image parameter and moves the image as the user moves the mouse pointer. After the user drops the image by releasing the mouse button, this method returns the result of the operation.
On the Mac OS, the returned value indicates a successful move (kODDropMove), a successful copy (kODDropCopy), or a failed drop (kODDropFail). On platforms that support asynchronous drag-and-drop operations, this method always returns kODDropUnfinished, indicating that the asynchronous operation has started.
When the drop is successful (the returned value is kODDropMove or kODDropCopy), the output parameter, destPart, contains a reference to the destination part; otherwise, the content of the destPart parameter is undefined. You should not call any of the destination part's methods except for its Release method.

EXCEPTIONS

kODErrNoDragManager
No platform-specific drag system service is available.

SEE ALSO
The ODByteArray type (page 877).
The ODDropResult type (page 922)
The ODEventData type (page 890).
The ODFrame::SetDragging method (page 333).
The ODPart::Drop method (page 506).
The ODPart::Release method (page 468).
"Adding Multistage Actions" on page 259 in OpenDoc Programmer's Guide.
"Initiating a Drag" on page 360 in OpenDoc Programmer's Guide.
"Completion of StartDrag" on page 368 in OpenDoc Programmer's Guide.